import {Callout} from "nextra/components";

# Getting Started

This guide assumes you have a basic understanding of Flutter and have already set up your development environment.
If you're new to Flutter, you may follow the official [installation guide](https://docs.flutter.dev/get-started).

## Installation

From your Flutter project directory, run the following command to install Forui.

<Callout type="warning">
  Forui 0.15.0+ requires Flutter **3.35.0+**. Run `flutter --version` to check your Flutter version.
</Callout>

```bash filename="bash" copy
flutter pub add forui
```

## Upgrading

Flutter does not automatically upgrade minor versions of packages prior to `1.0.0`.

This means that that following entry in your `pubspec.yaml` file will **not** automatically upgrade to `0.15.0`:

```yaml filename="pubspec.yaml"
dependencies:
  forui: ^0.15.0 // ❌ will not upgrade to 0.16.0
```

To upgrade to the latest version of Forui, run the following command:

```bash filename="bash" copy
flutter pub upgrade forui --major-versions
```

### Forui Icons

<Callout type="info">
    Forui Icons is bundled with the forui package. You don't need to install it separately if you install `forui`.
</Callout>

If you would like to only use the icons, run the following command from your Flutter project's directory.

```bash filename="bash" copy
flutter pub add forui_assets
```

## Usage

To use Forui widgets in your Flutter app, import the Forui package and place the
[`FAnimatedTheme`](https://pub.dev/documentation/forui/latest/forui.theme/FAnimatedTheme-class.html) widget underneath
`CupertinoApp`, `MaterialApp`, or `WidgetsApp` at the root of the widget tree.

To generate a basic Forui app structure in your project, run:

```bash filename="bash" copy
dart run forui init
```

Or copy & paste the following code snippet:

````dart filename='main.dart' copy
import 'package:flutter/material.dart';
import 'package:forui/forui.dart';

void main() {
  runApp(const Application());
}

class Application extends StatelessWidget {
  const Application({super.key});

  @override
  Widget build(BuildContext context) {
    /// Try changing this and hot reloading the application.
    ///
    /// To create a custom theme:
    /// ```shell
    /// dart forui theme create [theme template].
    /// ```
    final theme = FThemes.zinc.dark;

    return MaterialApp(
      // TODO: replace with your application's supported locales.
      supportedLocales: FLocalizations.supportedLocales,
      // TODO: add your application's localizations delegates.
      localizationsDelegates: const [...FLocalizations.localizationsDelegates],
      // MaterialApp's theme is also animated by default with the same duration and curve.
      // See https://api.flutter.dev/flutter/material/MaterialApp/themeAnimationStyle.html for how to configure this.
      //
      // There is a known issue with implicitly animated widgets where their transition occurs AFTER the theme's.
      // See https://github.com/forus-labs/forui/issues/670.
      theme: theme.toApproximateMaterialTheme(),
      builder: (_, child) => FAnimatedTheme(data: theme, child: child!),
      // You can also replace FScaffold with Material Scaffold.
      home: const FScaffold(
        // TODO: replace with your widget.
        child: Example(),
      ),
    );
  }
}

class Example extends StatefulWidget {
  const Example({super.key});

  @override
  State<Example> createState() => _ExampleState();
}

class _ExampleState extends State<Example> {
  int _count = 0;

  @override
  Widget build(BuildContext context) => Center(
    child: Column(
      mainAxisSize: MainAxisSize.min,
      spacing: 10,
      children: [
        Text('Count: $_count'),
        FButton(
          onPress: () => setState(() => _count++),
          suffix: const Icon(FIcons.chevronsUp),
          child: const Text('Increase'),
        ),
      ],
    ),
  );
}

````

It is perfectly fine to use Cupertino/Material widgets alongside Forui widgets!

```dart filename="main.dart" {3,12-18} copy
import 'package:flutter/cupertino.dart';

import 'package:forui/forui.dart';

void main() {
  runApp(const Application());
}

class Application extends StatelessWidget {
  const Application({super.key});

  Widget build(BuildContext context) => CupertinoApp(
    builder: (context, child) => FAnimatedTheme(
      data: FThemes.zinc.light,
      child: child!,
    ),
    home: FScaffold(...)
  );
}
```

### Themes

Forui provides a set of predefined themes that you can use out of the box.
In the example above, we used the `FThemes.zinc.light` theme, which is a light theme variant of the zinc color scheme.

Themes are a very powerful building block in Forui, allowing you to customize the look and feel of your app.
To learn more about themes, refer to the [Themes](/docs/themes) page.
